Skip to content

docs(lavaflow): explain repository CI consent - #198

Open
swkeever wants to merge 10 commits into
mainfrom
skeever/lavaflow-repository-ci-consent
Open

swkeever wants to merge 10 commits into
mainfrom
skeever/lavaflow-repository-ci-consent

Conversation

@swkeever

@swkeever swkeever commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

LavaFlow's normal repository CI requires both release availability and an explicit owner grant for the connected repository and GitHub installation. Document the dashboard grant/revoke flow, unchanged defaults, credential access before review, legacy fallback, installation changes, and the optional displayed-repository precondition.

The disclosure explicitly includes draft PRs, fixes whose LavaFlow review did not pass, and fixes held for a person to review, addressing Shawn's review of Hosting #3449.

Coordinates with https://github.com/Kong/volcano-hosting/pull/3449 and https://github.com/Kong/volcano-web/pull/1224. This PR targets main and includes the normal-CI documentation still in #197. Its three-file GitHub diff has been checked after integrating #197's branch; if #197 merges first, refresh the base and confirm the final diff again. Publish only when the opt-in implementation and production CI activation are live; auto-merge remains off.

Validation: pnpm lint (existing sidebar warnings only), pnpm lint:docs content, pnpm check:links, and pnpm build pass under Node 24. The history-only integration of #197 changed no content; GitHub Files changed remains limited to CLI LavaFlow, API capabilities, and the LavaFlow guide.

@swkeever
swkeever marked this pull request as ready for review November 16, 2026 21:53
@swkeever
swkeever requested review from shawnwu-kong and a balanced review from Copilot November 16, 2026 21:53

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

AI review: no P0-P2 findings

Reviewed 7a8afc9. Run log

Docs-only change. It documents LavaFlow's opt-in normal repository CI for fixes a person merges: the lavaflow.repository_ci capability, the owner's dashboard and API grant and revoke flow through allow_ungated_workflows, binding the grant to the repository and installation, the expected_repository precondition and its 409 repository_changed, and the credential disclosure on the CLI page. This head fixes every earlier finding: the guarded-path instructions are back under "Without normal repository CI", the CI-skip section names the guarded path and is linked again, the error-table row is added, the example IDs match the page's own settings response, and the dashboard's button and switch are both explained. Risk is low. One wording nit remains.

⚪ P3

  • content/platform/guides/lavaflow.md:2350 Default guarded path is also called the "earlier publication path", which reads as historical

Not checked: The AI review read the diff, the code, and the PR's text; it ran no tests or builds and read nothing outside this repository.

  • Whether production GET /capabilities serves lavaflow.repository_ci and the opt-in behavior is live; spec/writing.md says to merge only after release.
  • Whether behavior matches volcano-hosting#3449: drafts keep CI, expected_repository returns 409 repository_changed, installation changes revoke, retries recheck.
  • Whether the dashboard labels Allow repository CI and Allow repository CI before review match what volcano-web#1224 renders.
  • Whether the warning the CLI prints for settings set --allow-ungated-workflows true matches the updated disclosure on the CLI page.
  • Confirm the coordinated hosting and dashboard releases are live before publishing, as required by spec/writing.md.

Human review: not needed

Comment thread content/platform/guides/lavaflow.md Outdated

LavaFlow's commit on a fix branch can carry a CI-skip directive, so your CI
Fixes opened with normal repository CI have no CI-skip directive.
For automatic merging or an older PR, LavaFlow's commit on a fix branch can carry a CI-skip directive, so your CI

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 P2: CI-skip guidance now limited to automatic merging or older PRs, but default-path fixes still carry the directive

This section now says the CI-skip directive applies only to "automatic merging or an older PR". Line 905 says that with permission off or lavaflow.repository_ci unavailable, LavaFlow uses the guarded path, where "commits skip CI initially". That is the default, since allow_ungated_workflows defaults to false, so new fixes a person merges still carry the directive. The PR also removed the only two links to this section: the intro note (old lines 21–22) and the pointer in Review and merge fixes yourself. Nothing on the site links here now. A reader on the default path who rebases or squash-merges with GitHub's default message can land the directive on the base branch, and push-triggered workflows such as deploys won't run. Fix: name the guarded publication path here ("on the guarded publication path, for automatic merging, or on an older PR"), and link back to this section from the guarded-path paragraph at line 905 and from the intro.

Found by claude-opus-5-5

Comment thread content/platform/guides/lavaflow.md Outdated
Check the review and CI results before merging.
LavaFlow never merges a fix opened for a person, even if you later enable automatic merging.

With permission off or normal repository CI unavailable, LavaFlow keeps the guarded publication path: commits skip CI initially and LavaFlow checks workflows before opening a PR or starting CI.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 P2: Rewrite drops how default-path fixes open, while other sections still point here for it

The old Review and merge fixes yourself text explained how a fix a person merges opens on the guarded path. It covered: the draft whose commit skips CI while the one-time start is unavailable; the ready-for-review PR with LavaFlow's one-time CI start and its comment; the CI-outside-Actions check that turns the PR into a draft; repositories that can't have drafts; and held fixes that open ready but still skip CI (push a commit to run it). The replacement is five general sentences ("Those PR descriptions tell you whether CI started and how to start it yourself"). Several sections still send readers here for those details: the draft_reason open_pr row (line 1635: "or the repository may run CI outside GitHub Actions … see Review and merge fixes yourself"), Check before CI starts (lines 2313–2314 and 2366–2369: "a fix it finds anything for opens as a draft. See Review and merge fixes yourself"), and the person_merges hold reason (line 1121). Since this path is what every project gets until the owner opts in, those readers can no longer learn whether their fix will be a draft or how to get CI to run. Fix: keep the earlier guarded-path paragraphs under their own subsection (for example "Without normal repository CI") and point those cross-references there.

Found by claude-opus-5-5

A repository rename that keeps both IDs keeps the permission.
Project access tokens and `volcano-config.yaml` cannot grant it.

Turn **Allow repository CI before review** off in LavaFlow settings to revoke permission, including while normal repository CI is unavailable.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚪ P3: Dashboard control named two different ways

The revoke step says to turn Allow repository CI before review off. The grant steps at lines 2405 and 2409, and the CLI page (content/cli/lavaflow.md:266), call it Allow repository CI. If both names refer to one dashboard control, at least one is wrong and readers won't find it. Use the label volcano-web#1224 actually renders in every place.

Found by claude-opus-5-5

code; gating them on a label a person adds is safer.
API callers can include `expected_repository: {"repo_id": 4242, "repo_installation_id": 7}`, using the IDs in the settings response's `repository` field.
This optional precondition is checked atomically with the save, including when permission is already on.
A mismatch returns `409` with `code: repository_changed` and changes nothing; review the current connection before sending a new request.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚪ P3: New 409 repository_changed and expected_repository are missing from the settings error table

This paragraph adds a request field, expected_repository, and a new error, 409 with code: repository_changed. The PATCH /lavaflow/settings error table under Settings (lines 553–569) still lists only a code-less 409 ("kept changing … send it again") and says an unknown field returns 400. A client built from that table would treat repository_changed as retryable and resend, but the new text says to review the connection first. Add a 409 | repository_changed row. Also, the example IDs (4242, 7) don't match the repository IDs in this page's own settings response (812345678, 52001234), even though the text says to copy them from there.

Found by claude-opus-5-5

Comment thread content/cli/lavaflow.md
the repository could run it, or put its text into a command, with the
repository's secrets before a person approves it: the fix stays on its run
instead. Only the project's owner can turn that on, signed in as a person:
Allow normal repository CI for initial PRs a person merges when the project's `lavaflow.repository_ci` capability is available.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚪ P3: CLI page doesn't mention CI on drafts, failed-review fixes, or held fixes

The guide's Allow ungated workflows section now says CI and previews may run generated code with credentials before review, including on draft PRs, fixes whose review didn't pass, and held fixes (guide lines 2430–2433). The PR description says this disclosure is the point of the change. The CLI section, where owners turn the permission on with settings set, still describes only the guarded-path risk ("Workflows in the repository may then run LavaFlow's pull requests … gating them on a label a person adds is safer"). It doesn't say that on the normal path LavaFlow doesn't check those gates. Add the same sentences, or link to them, so the CLI page describes what the grant now allows.

Found by claude-opus-5-5

### Check before CI starts

A fix opens with a commit that skips CI. Under `autonomy: merge`, once its
This section applies to automatic merging and the earlier publication path.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚪ P3: Default guarded path is also called the "earlier publication path", which reads as historical

Line 909 defines the default path for projects without the owner's grant as the guarded publication path, and lines 1310, 2139 and 2486 use that name. About ten other places use earlier publication path for what appears to be the same path: lines 424, 1105, 1107, 1137, 1166, 1680, 2350, 2358 and 2411. Line 2358 also calls it the "legacy CI-start release". Every project whose owner hasn't granted permission is still on this path. A reader of Check before CI starts ("This section applies to automatic merging and the earlier publication path") or of the CI-message table at line 424 could take "earlier" to mean the text no longer applies to them and skip it. Pick one name, ideally "guarded publication path", and use it everywhere. Keep "earlier one-time CI start" only for the one-time-start variant inside that path.

Found by claude-opus-5-5

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants